juce/source/extras/audio plugins/How to use this framework.txt

   1
   2                             The Juce Polymorphic Plugin Project!
   3                             ====================================
   4
   5 (c) 2008 by Raw Material Software, visit www.rawmaterialsoftware.com for more info.
   6
   7 -----------------------------------------------------------------------------------------------------
   8
   9 This file contains as much detail as I could possibly think of about the sometimes fiddly process of setting
  10 up your build environment to build plugins...
  11
  12 If you follow all these steps and still hit a build error, don't despair! There's a thread at the juce
  13 forum where we'll post any extra hints, tips, or problems that people have stumbled upon:
  14 http://www.rawmaterialsoftware.com/juceforum/viewtopic.php?p=23546
  15
  16
  17 -----------------------------------------------------------------------------------------------------
  18
  19 The purpose of this framework is to make is simple to write an audio plugin in a generic
  20 way, which can then be compiled as a VST, AudioUnit, RTAS, or any combination of these.
  21
  22 It's "polymorphic" because the output is a single binary module that acts as all of the
  23 different plugin formats at the same time. This means that you only need to maintain one
  24 project, and only need to perform one build to create a multi-format plugin.
  25
  26 Also included are some helper classes that make it easy to create a stand-alone app to
  27 run your plugin without a host. This might be useful in its own right, but can also be very
  28 handy when developing your plugin, because you can build, test and debug it without needing
  29 to keep restarting a 3rd-party host.
  30
  31
  32                                     How does it work?
  33                                     =================
  34
  35 To create your plugin, you just create a subclass of the AudioPluginInstance class to
  36 perform the processing. And your plugin UI is written like any normal Juce UI component.
  37
  38 All the platform-specific code is hidden away in wrapper classes that you just add to
  39 your project - you should (hopefully) never need to even see the inner workings of these.
  40
  41
  42                                     Licensing issues
  43                                     ================
  44
  45 Juce is released under the GPL (Gnu Public License) - this means that you're free to use
  46 and redistribute it as long as your products are also released under the GPL. Basically
  47 this means that if you use it, you also have to give away your source code.
  48 If you want to release a closed-source application, you can buy a commercial license
  49 that lets you avoid this restriction - see http://www.rawmaterialsoftware.com/juce for more info,
  50 or see the comments at the top of all the Juce source files.
  51
  52 If you're building the VST projects or releasing a VST, you'll need have a look at Steinberg's
  53 developer site to see what licensing rules apply these days. Their website's at
  54 http://www.steinberg.net
  55
  56 If you're building an RTAS then you'll need to sign Digidesign's developer license to get
  57 their SDK. Visit http://www.digidesign.com for more info.
  58
  59
  60
  61                                     Getting Started
  62                                     ===============
  63
  64 There's also a 'demo' folder - this contains an example plugin which can be built in all
  65 the different formats.
  66
  67 Have a look at the demo classes to see how it works, and then to create a real plugin,
  68 you'll need to replace the demo files with your own code.
  69
  70 I've tried to add helpful comments where you might run across common compile errors, to
  71 help describe what you might be doing wrong, as getting a build set-up for some of these
  72 formats can be a bit of a pain. Please let me know if you find there's anything missing
  73 from these instructions or anything I could change to help smooth the build process along
  74 a bit.
  75
  76 I'd recommend NOT putting your own plugin code inside the demo plugin directory - it's
  77 much neater to keep it somewhere separate and to alter the projects to point to your
  78 files instead of the demo ones. That way when new versions of this library come out, it'll
  79 make it easier to update to the latest code.
  80
  81
  82 -----------------------------------------------------------------------------------------------------
  83
  84                             Prerequisites for building a VST
  85                             ================================
  86
  87 - Visit http://www.steinberg.net and jump through whatever hoops are necessary to download
  88   and install the VST SDK.
  89 - Make sure your include path contains an entry for the "vstsdk2.4" folder containing the SDK.
  90
  91 -----------------------------------------------------------------------------------------------------
  92
  93                             Prerequisites for building an RTAS
  94                             ==================================
  95
  96 - Contact Digidesign, ask to become a Digidesign Development Partner, sign the relevent
  97   agreements and NDAs.
  98 - From the Digidesign website, download their latest Plug-In SDK
  99 - Install the SDK and build some of the demo plugins to make sure it all works.
 100 - In Visual Studio: Add all of these to your include path:
 101     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\EffectClasses
 102     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses
 103     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses\Interfaces
 104     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Utilities
 105     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\RTASP_Adapt
 106     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\CoreClasses
 107     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Controls
 108     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Meters
 109     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ViewClasses
 110     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\DSPClasses
 111     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Interfaces
 112     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\common
 113     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\common\Platform
 114     c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\SignalProcessing\Public
 115     C:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugIns\DSPManager\Interfaces
 116     c:\yourdirectory\PT_80_SDK\AlturaPorts\SADriver\Interfaces
 117     c:\yourdirectory\PT_80_SDK\AlturaPorts\DigiPublic\Interfaces
 118     c:\yourdirectory\PT_80_SDK\AlturaPorts\Fic\Interfaces\DAEClient
 119     c:\yourdirectory\PT_80_SDK\AlturaPorts\NewFileLibs\Cmn
 120     c:\yourdirectory\PT_80_SDK\AlturaPorts\NewFileLibs\DOA
 121     c:\yourdirectory\PT_80_SDK\AlturaPorts\AlturaSource\PPC_H
 122     c:\yourdirectory\PT_80_SDK\AlturaPorts\AlturaSource\AppSupport
 123     c:\yourdirectory\PT_80_SDK\AvidCode\AVX2sdk\AVX\avx2\avx2sdk\inc
 124     C:\yourdirectory\PT_80_SDK\xplat\AVX\avx2\avx2sdk\inc
 125 - In Visual Studio: Using the Digidesign demo projects in the SDK, make sure you've compiled
 126   debug and release versions of the following static libraries:
 127     DAE.lib, DigiExt.lib, DSI.lib, PlugInLib.lib.
 128 - In XCode: After installing the Digidesign SDK, make sure you've run the config_SDK_for_Mac
 129   command in the SDK's root directory. This sets up some of the tools that it needs.
 130 - In XCode: If you're using the Digi files CommonDebugSettings.xcconfig and CommonReleaseSettings.xcconfig,
 131   then you'll probably have to remove the "-x c++" option from their OTHER_CFLAGS setting, because
 132   that prevents it compiling obj-C. Also, you might need to comment-out the GCC_PREFIX_HEADER setting,
 133   unless you can persuade precompiled headers to work (I've never managed to get them working myself..)
 134   You'll also probably want to add a "MacBag" setting to these files, rather than putting it into
 135   your project - e.g. "MacBag = /Users/jules/SDKs/PT_80_SDK/MacBag"
 136
 137
 138 -----------------------------------------------------------------------------------------------------
 139
 140                         Choosing the formats to build
 141                         =============================
 142
 143 Each plugin project needs to contain a JucePluginCharacteristics.h file, which holds all the
 144 plugin-specific build details. In here, there are three macros that you can set to enable each
 145 of the available formats:
 146
 147 #define JucePlugin_Build_VST     1
 148 #define JucePlugin_Build_RTAS    1
 149 #define JucePlugin_Build_AU      1
 150
 151 You can set these to 0 to disable the formats that you don't want to build, and this will avoid
 152 any compilation problems if, for example, you don't have the appropriate SDK for a particular format.
 153
 154 -----------------------------------------------------------------------------------------------------
 155
 156                         Creating a PC VST/RTAS plugin in Visual Studio
 157                         ==============================================
 158
 159
 160 - First try loading the VST demo project in JuceAudioPlugin/demo/build. Hopefully this
 161   should build correctly.
 162 - Create a new, empty, win32 project using Visual Studio. Choose "DLL" as the type of
 163   product to build
 164 - If building an RTAS, add to your project all the juce_RTAS_*.cpp files from the wrapper/RTAS folder.
 165 - If building a VST, add to your project all the juce_VST_*.cpp files from the wrapper/VST folder.
 166
 167 - Create yourself a JucePluginCharacteristics.h file, starting with a copy of the one in the
 168   demo project. Go through each item inside it carefully, and set them to the appropriate value
 169   for your plugin.
 170
 171 - Under "Additional Include Directories", add the folder in which you're going to put
 172   your JucePluginCharacteristics.h file.
 173
 174 - If you're doing an RTAS, change these project settings (these can all be ignored if you're only doing a VST):
 175     - Set "C++/Code Generation/Runtime Library" to be "Multi-threaded DLL" or "Multi-threaded Debug DLL"
 176     - Set the "Linker/Input/Module Definition file" to point to "wrapper/RTAS/juce_RTAS_WinExports.def"
 177     - Under "Linker/Input/Delay loaded DLLs", add the following:
 178         "DAE.dll; DigiExt.dll; DSI.dll; PluginLib.dll; DSPManager.dll"
 179     - You may (or may not) need to add "libcmtd.lib; libcmt.lib" to the "Linker/Input/Ignore Specific Library" setting.
 180     - For ONLY the following files:
 181         juce_RTAS_Wrapper.cpp, juce_RTAS_DigiCode1.cpp, juce_RTAS_DigiCode2.cpp, juce_RTAS_DigiCode3.cpp,
 182       change their "C++/Advanced/Calling Convention" property to "__stdcall". All other files should
 183       be left with the default calling convention of "__cdecl"
 184     - Set the "Linker/General/Output File" property to "$(OutDir)\$(ProjectName).dpm" (If you're building
 185       a polymorphic VST/RTAS, then you can simply copy or rename the finished .dpm file to a .dll, and
 186       it'll function as a VST)
 187     - Under "Custom build step", add the following command:
 188         copy /Y "\yourdirectory\juce\extras\audio plugins\wrapper\RTAS\juce_RTAS_WinResources.rsr" "$(TargetPath)".rsr
 189       The corresponding "Outputs" setting for this must be set to "$(TargetPath)".rsr
 190       (This will copy and rename the juce_RTAS_WinResources.rsr file to sit next to the finished .dpm file. It's
 191       a dummy resource file, but PT will refuse to load the plugin unless it has a corresponding .rsr file)
 192     - Because the RTAS code duplicates some win32 constants, you might need to force it to link correctly
 193       by adding "/FORCE:multiple" to the linker's additional command line options.
 194     - You might want to change the output directory to "\Program Files\Common Files\Digidesign\DAE\Plug-Ins\"
 195       if you want the built plugin to go directly into the PT plugins folder
 196     - When setting properties, remember to change them for both your debug and release builds!
 197
 198 - Create your actual plugin classes and add them to the project. Obviously this is the hard bit!
 199
 200 - Add the amalgamated juce source file to the project - have a look at the demo app for neat ways of doing this.
 201
 202 - NOTE: on Windows, because RTAS uses the altura mac-style code, there are annoying clashes caused if
 203   you also include the Apple QuickTime headers, so you might need to turn off quicktime by setting the
 204   juce config macro: #define JUCE_QUICKTIME 0
 205
 206 - NOTE: If you're using MSVC2005 to build your plugin, the users will need to
 207   have the Microsoft VC8 Runtime installed on their machines, otherwise the DLL will
 208   silently fail to load. You should probably add the runtime to your plugin's installer,
 209   and you can get a copy of it here:
 210   http://www.microsoft.com/downloads/details.aspx?FamilyID=32bc1bee-a3f9-4c13-9c99-220b62a191ee&DisplayLang=en
 211
 212
 213
 214 -----------------------------------------------------------------------------------------------------
 215
 216                             Creating a Mac AU/VST/RTAS plugin in XCode
 217                             ==========================================
 218
 219
 220 - Some of the RTAS SDK files in the demo project might be highlighted red to indicate that they're
 221   missing - if you're not bulding an RTAS, then you can just delete them from the project. If you are
 222   building an RTAS and have the SDK, you might need to update their paths to match your SDK location.
 223 - For an AU, there are a bunch of Apple cpp files that need to be included directly in your project - these
 224   used to be found in /Developer/Examples/CoreAudio/ but in the 10.6 SDK, Apple have moved them to a slightly
 225   more sensible location at /Developer/Extras/CoreAudio. The Juce demo is hardwired to refer to their new
 226   10.6 location, so if you haven't yet installed the 10.6 SDK, the easiest way to make it all happy is just
 227   to duplicate your /Developer/Examples/CoreAudio folder as /Developer/Extras/CoreAudio. That way old and new
 228   juce plugin projects will all compile without changing any project paths.
 229 - For an AU, make sure that the JucePlugin_Build_AU is enabled in your JucePluginCharacteristics.h
 230 - In XCode, create a new project based on the "Audio Unit Effect" template
 231 - XCode will create a bunch of template source files for you - you can remove all of these from the project
 232   and delete them
 233 - In the target settings, clear the "Exported Symbols File" setting. The exports are specified by directives
 234   within the wrapper code, so don't need to be listed explicitly.
 235 - All all the Apple frameworks that Juce normally requires to the "External Frameworks" list
 236 - Add all the juce_AU_* files from the /wrapper/AU directory to your project
 237 - The template project creates an AUPublic group that contains lots of AudioUnit source files. But
 238   it leaves out files that it thinks you might not need, e.g. if you chose an "Audio Unit Effect" project,
 239   then it won't add the classes for handling MIDI. So you'll probably need to go into this folder
 240   and check that it contains AUMIDIBase.cpp, AUMidiEffectBase.cpp, MusicDeviceBase.cpp, etc
 241 - As for the PC, you'll need to make sure your project contains a correctly set-up JucePluginCharacteristics.h
 242   file - start with a copy of the one in the demo plugin project, and go through it making sure that
 243   all the values make sense for your plugin.
 244 - The JucePluginCharacteristics.h file is included not only by the code, but also by the resources files - so it
 245   needs to be locatable on both your normal header search path, and also on your resource include path, which is
 246   the project setting called 'Rez Search Paths'
 247 - Because of the flat naming structure used by Objective-C, if a host loads several different plugins which
 248   all contain slightly different versions of the juce library, you can get nasty situations where all their obj-C
 249   classes are cross-linked to the similarly-named class in other modules, and everything turns into a big mess...
 250   To avoid this, you're advised to set a unique JUCE_ObjCExtraSuffix value (you'll find this in juce_mac_NativeCode.mm,
 251   or if you're using the amalgamated version, you can just set it before including juce_amalgamated.cpp). Choose a
 252   suffix that's unique to both the name and version of your plugin.
 253 - Create your actual plugin classes and add them to the project. Obviously this is the hard bit!
 254
 255 You should now be able to build a functional AU! If you want VST support as well, then read on...
 256
 257 - Make sure that the JucePlugin_Build_VST is enabled in your JucePluginCharacteristics.h
 258 - For VST support, add all the juce_VST_* files from /wrapper/VST
 259 - In your target info settings, add the vstsdk2_4 folder to your "Header Search Paths" list
 260 - Make sure that in your Info.plist, the "Bundle Name" value is correctly set to the name of your plugin.
 261
 262 Now, if you compile, the resulting bundle should work as both a VST and AU - you can simply copy or rename it,
 263 changing the suffix to ".vst", and put it in your VST folder.
 264
 265 NOTE! In order to copy and rename the plugin to the various different plugin folders, the demo plugin project
 266 contains a VERY useful script, which you'll almost certainly want to copy into your own projects - have
 267 a look in the demo target for the build phase called "Copy into the different plugin folders", and use the
 268 inspector to have a look at the script. It uses advanced cunningness to copy only to the correct target
 269 folders for the types of plugin you're targeting, and should be able to be used in your own project
 270 without needing to edit it.
 271
 272 NOTE! If you use the Finder to rename your xyz.component file to xyz.vst, it might look like it's done
 273 exactly this... but in fact, the Finder may have secretly renamed it as "xyz.vst.component", even though
 274 it shows "xyz.vst" as the name on the screen. I have wasted quite a lot of time angrily wondering why my VSTs
 275 don't seem to work, before realising that this is what has happened. You should use the command-line to rename
 276 it correctly.
 277
 278 If you also want to build an RTAS, then carry on reading...
 279
 280
 281 - Make sure that the JucePlugin_Build_RTAS is enabled in your JucePluginCharacteristics.h
 282 - After installing the Digidesign SDK, make sure you've run the config_SDK_for_Mac command in
 283   its root directory. This sets up some of the tools that it needs.
 284 - Add the files from /wrapper/RTAS to your project. Obviously a couple of these are for Windows, so
 285   you shouldn't add those
 286 - In the Digi SDK, in /AlturaPorts/TDMPlugins/common/mac, there are two config files:
 287     CommonDebugSettings.xconfig and CommonReleaseSettings.xconfig
 288   These contain lots of Digi hackery to get their stuff to compile, so you should add them to your project
 289   and change your project's settings to use these files as their base config. Even so, it's all a bit of a mess,
 290   and you may need to tweak them a bit to get it to work on your system.
 291 - In your target settings, add a custom build setting called "MacBag", and set this to the path where the
 292   "MacBag" folder of the Digi SDK lives.
 293 - Add the following to your "Header Search Paths" setting (it's easiest to copy-and-paste this setting from
 294   the demo project):
 295     "$(MacBag)/../AlturaPorts/TDMPlugIns/PlugInLibrary/**"
 296     "$(MacBag)/../AlturaPorts/TDMPlugIns/DSPManager/**"
 297     "$(MacBag)/../AlturaPorts/TDMPlugIns/SupplementalPlugInLib/Encryption"
 298     "$(MacBag)/../AlturaPorts/TDMPlugIns/SupplementalPlugInLib/GraphicsExtensions"
 299     "$(MacBag)/../AlturaPorts/TDMPlugIns/common"
 300     "$(MacBag)/../AlturaPorts/TDMPlugIns/common/PI_LibInterface"
 301     "$(MacBag)/../AlturaPorts/TDMPlugIns/PACEProtection/**"
 302     "$(MacBag)/../AlturaPorts/OMS/Headers"
 303     "$(MacBag)/../AlturaPorts/Fic/Interfaces/**"
 304     "$(MacBag)/../AlturaPorts/Fic/Source/SignalNets"
 305     "$(MacBag)/../AlturaPorts/DSIPublicInterface/PublicHeaders"
 306     "$(MacBag)/../DAEWin/Include"
 307     "$(MacBag)/../AlturaPorts/DigiPublic/Interfaces"
 308     "$(MacBag)/../AlturaPorts/DigiPublic"
 309     "$(MacBag)/../AlturaPorts/NewFileLibs/DOA"
 310     "$(MacBag)/../AlturaPorts/NewFileLibs/Cmn"
 311     "$(MacBag)/../AlturaPorts/TDMPlugIns/SignalProcessing/**"
 312     "$(MacBag)/../AvidCode/AVX2sdk/AVX/avx2/avx2sdk/inc"
 313     "$(MacBag)/../AvidCode/AVX2sdk/AVX/avx2/avx2sdk/utils"
 314 - If you get include errors compiling some of the DigiDesign code, you may need to
 315   add "/Developer/Headers/FlatCarbon" to your header search path.
 316 - In the SDK, find the PluginLibrary.xcodeproj file, and add this to your "External frameworks and Libraries".
 317   If you've already compiled this library, you can open its item in your XCode project treeview, to find
 318   the "libPluginLibrary.a" item inside it. Drag this subitem down to your Target/"Link Binary With Libraries"
 319   build stage and drop it there to add it to the link process.
 320 - In your Info.plist, change the "Bundle OS Type Code" to "TDMw", and the "Bundle Creator OS Type Code" to
 321   "PTul".
 322 - You may need to remove the "OTHER_CFLAGS = -x c++" from the RTAS settings file to stop it complaining about
 323   obj-C code
 324
 325 You should now be able to build an RTAS! Again, just renaming the finished bundle to ".dpm" and
 326 putting it in your RTAS folder should be do the trick.
 327
 328 If you get any weird build problems, a good tip is to try comparing the demo plugin's build settings with your
 329 own - this should usually show up what's missing.
 330
 331
 332 Note about exported symbols:
 333   When XCode builds the plugin, I've had unpredictable results when trying to stop it from exporting
 334   all of the internal functions as public symbols. There are some flags that are supposed to turn this
 335   off, but sometimes they don't seem to have any effect, and using an explicit exports file also
 336   seems a bit hit-and-miss. (If anyone knows better and can get this working, please let me know!)
 337   Anyway, as well as being wasteful and showing everyone what's inside your plugin, leaving all
 338   the symbols in there will cause fatal crashes when used with Tracktion, or alongside any other
 339   Juce-based plugins. A way of making sure your plugin is stripped is to use the command
 340   "strip -x -S YourPlugin.vst/Contents/MacOS/YourPlugin" after bulding it, which removes the
 341   unnecessary symbols (although in my experience this also doesn't seem to work all the time,
 342   so it's a good idea to check it using the unix "nm" command).